#-*- coding: utf-8 -*-

#This file is part of pyLot library.
#
# pyLot is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# pyLot is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with pyLot.  If not, see <http://www.gnu.org/licenses/>.

__author__ = u'Pierre Puiseux, Guillaume Baty'
__copyright__ = u"Copyright 2011-2012 (C) andheo, Université de Pau et des Pays de l'Adour"
__credits__ = [u'Pierre Puiseux', u'Guillaume Baty']
__license__ = "GNU Lesser General Public License"

__all__ = ['CliCorePlugin']

from traits.api import List
from envisage.api import ExtensionPoint

from pyLot.core import CorePlugin
from .interfaces.i_climodifier import ICliModifier, ICli

class CliCorePlugin(CorePlugin):
  u"""
  CliCorePlugin provide extension points for command lines arguments
  (like --do-action or --set-param-a=1).
  
  Command line may affect different parts of program at different moments.
  For example, a frontend selector (gtk, qt, ncurse, ...) must be called 
  **after** core initialization to know what frontend are availabe but 
  **before** frontend initialization (because it depends on these arguments).
  
  Keeping this frontend example, a command line specific to qt frontend 
  (like use tabs instead of docks or launch wizard/splashscreen/tips/... 
  at start) must be launched **after** frontend initialization.
  
  For theses reasons, you should define several extension points corresponding
  to different moment and target.
  
  For example : 
  
    - **level 0** is before application initialization so it cannot appear as
  extension point (extension point mechanism is not yet initialized). 
  This level is generally used to change library core behaviour
  generally for debugging purposes.  

    - **level app** is just after application initialization. This level is 
    generally used to change APPLICATION properties. target is APPLICATION.
    - **level app_stop** is once application is finished. This level is
    generally the last called.

    - **level backend_1** is before backend initialization. It has no targets.
    - **level backend_2** is during backend initialization. Target is backend.
    - **level backend_3** is after backend initialization. Target is backend.
    - **level backend_stop** is once backend is finished. Target is backend.
    
    - **level frontend_1** is before frontend initialization. It has no targets.
    ...


  Application may not use all levels. For example a command line application
  only uses level app* and backend*. Other applications may define additional
  levels like frontend_gtk or backend_gstreamer  ...
  
  Remember that each climodifier has three levels of modification :
    - standalone modification
    - target **class** modification (ie before object creation)
    - target **instance** modification (ie when creation is finished)
   and a constructor that generate all --args.

  """
  clis_app = ExtensionPoint(List(ICliModifier), id='pyLot.cli.modifiers_app')
  clis_handler = ExtensionPoint(List(ICli), id='pyLot.cli.modifiers_backend')
